OpenEdge Development:<br />Programming Interfaces SAX callback reference

Release 10.1A: OpenEdge Development:
Programming Interfaces

SAX callback reference

This section contains a reference entry for each callback Progress SAX supports. Each entry specifies the signature and defines each parameter.

The callbacks, in alphabetical order, are:

Characters

EndDocument

EndElement

EndPrefixMapping

Error

FatalError

IgnorableWhitespace

NotationDecl

ProcessingInstruction

ResolveEntity

StartDocument

StartElement

StartPrefixMapping

UnparsedEntityDecl

Warning

These callbacks closely match those defined in the SAX2 documentation at www.saxproject.org. For more information on these callbacks, see this Web site.

Characters

Invoked when the XML parser detects character data.
Syntax
PROCEDURE Characters:
  DEFINE INPUT PARAMETER charData AS { MEMPTR | LONGCHAR}. 
  DEFINE INPUT PARAMETER numChars AS INTEGER. 
charData
A MEMPTR or LONGCHAR that contains a chunk of character data.
numChars
The number of characters contained in the MEMPTR.
Note: If a character requires more than one byte to encode, the value of numChars might not match the value returned by MEMPTR:GETSIZE().

The parser calls this method to report each chunk of character data. It might report contiguous character data in one chunk, or split it into several chunks. If validation is enabled, whitespace is reported by the IgnorableWhitespace callback.

Although it is not intended for the application to call Characters directly, the application can. Whoever calls Characters must free the charData MEMPTR. When Progress calls Characters, Progress is responsible for freeing the charData MEMPTR (although if the application frees it, no harm results). If the application calls Characters, the application is responsible for freeing the charData MEMPTR.

To copy the charData MEMPTR such that the memory used by the copy is completely separate from the memory used by the original, use 4GL assignment, which performs a deep copy. The following fragment demonstrates this:
memptrA = memptrB 
For more information on 4GL assignment, see the OpenEdge Development: Progress 4GL Reference .

EndDocument

Invoked when the XML parser detects the end of an XML document.
Syntax
PROCEDURE EndDocument: 
EndElement

Invoked when the XML parser detects the end of an element.
Syntax
PROCEDURE EndElement:
  DEFINE INPUT PARAMETER namespaceURI AS CHARACTER. 
  DEFINE INPUT PARAMETER localName    AS CHARACTER. 
  DEFINE INPUT PARAMETER qName        AS CHARACTER. 
namespaceURI
A CHARACTER string indicating the namespace URI of the element.

If namespace processing is not enabled, or the element is not part of a namespace, the string is of length zero.
localName
A CHARACTER string indicating the nonprefixed element name.

If namespace processing is not enabled, the string is of length zero.
qName
A CHARACTER string indicating the actual name of the element in the XML source.

If the name has a prefix, qName includes it, whether or not namespace processing is enabled.

This callback corresponds to a preceding StartElement after all element content is reported.

EndPrefixMapping

Invoked when the XML parser detects that a prefix associated with namespace mapping has gone out of scope.
Syntax
PROCEDURE EndPrefixMapping:
  DEFINE INPUT PARAMETER prefix AS CHARACTER. 
prefix
A character string representing the prefix for a namespace declaration.

This callback is invoked only when namespace processing is enabled. It provides information not required by normal namespace processing. However, in some situations, this callback might be useful and even required.

Error

Invoked to report an error encountered by the parser while parsing the XML document.
Syntax
PROCEDURE Error:
  DEFINE INPUT PARAMETER errMessage AS CHARACTER.  
errMessage
A character string indicating the error message.

After this callback is invoked, the parser continues where it left off.

FatalError

Invoked to report a fatal error.
Syntax
PROCEDURE FatalError:
  DEFINE INPUT PARAMETER errMessage AS CHARACTER.  
errMessage
A character string indicating the error message.

The application must assume that after a fatal error is reported, the document is unusable and future parsing events might not be reported. However, the parser might try to continue to parse the document. To stop the parser after reporting a fatal error, execute RETURN ERROR.
Note: If you stop the parser by executing STOP-PARSING(), parsing stops, but no error condition is raised, no error message is reported, SAX-reader’s PARSE-STATUS attribute is set to SAX-COMPLETE rather than to SAX-PARSER-ERROR, and the driver might not know that an error occurred. For this reason, Progress Software Corporation recommends that to stop the parser after reporting a fatal error, execute RETURN ERROR.

IgnorableWhitespace

Invoked when the XML parser detects ignorable whitespace.
Syntax
PROCEDURE IgnorableWhitespace:
  DEFINE INPUT PARAMETER charData AS CHARACTER. 
  DEFINE INPUT PARAMETER numChars AS INTEGER. 
charData
A CHARACTER string representing a contiguous block of ignorable whitespace in an XML document.
numChars
An INTEGER expression indicating the size, in characters, of the character string.

If validation is enabled, the XML parser reports ignorable whitespace through this callback. If validation is not enabled, the XML parser reports whitespace through the Characters callback.

The data type of charData is CHARACTER, not MEMPTR, because it is unlikely that an XML document has over 32K of contiguous ignorable whitespace.

NotationDecl

Invoked when the XML parser detects a notation declaration.
Syntax
PROCEDURE NotationDecl:
  DEFINE INPUT PARAMETER name     AS CHARACTER. 
  DEFINE INPUT PARAMETER publicID AS CHARACTER. 
  DEFINE INPUT PARAMETER systemID AS CHARACTER. 
name
A character string representing the name of the notation.
publicID
Optional. A character string indicating the public identifier of the entity.

If none is supplied, the string is of length zero.
systemID
Optional. A character string indicating the system identifier of the entity.

If none is supplied, the string is of length zero.

systemID must be one of the following:

Absolute file path

Relative file path

Absolute URI

ProcessingInstruction

Invoked when the XML parser detects a processing instruction.
Syntax
PROCEDURE ProcessingInstruction:
  DEFINE INPUT PARAMETER target AS CHARACTER. 
  DEFINE INPUT PARAMETER data   AS CHARACTER. 
target
A character string indicating the target of the processing instruction.
data
A character string indicating the data associated with the processing instruction.

If the processing instruction has no data, the length of the string is zero.
Note: A processing instructions can appear before or after a root element.

ResolveEntity

Invoked to let the application specify the location of an external entity (such as a DTD or XML schema).

When the parser finds an external entity reference, it calls ResolveEntity, passing it the system identifier and public identifier (if any) contained in the XML. This gives the application a chance to override the location specified in the XML.
Note: In ResolveEntity, you cannot use any I/O blocking statements, such as the UPDATE statement and the WAIT-FOR statement.
Syntax
PROCEDURE ResolveEntity:
  DEFINE INPUT  PARAMETER publicID   AS CHARACTER. 
  DEFINE INPUT  PARAMETER systemID   AS CHARACTER. 
  DEFINE OUTPUT PARAMETER filePath   AS CHARACTER.
  DEFINE OUTPUT PARAMETER memPointer AS { MEMPTR | LONGCHAR}. 
publicID
Optional. A character string indicating the public identifier of the entity. If none is supplied, the string is of length zero.
systemID
A character string indicating the system identifier of the entity.

The character string will not be of length zero, as this parameter is required.

systemID will be one of the following:

Absolute file path

Relative file path

Absolute URL

filePath
Optional. A character string indicating the actual location of the entity being resolved. This tells the parser where to actually get the entity, in preference to the location specified by the system identifier.

filePath will be one of the following:

Absolute file path

Relative file path

HTTP URI

If you do not supply filePath, set it to the Unknown value (?).

memPointer
Optional. A MEMPTR or LONGCHAR containing the entity being resolved. Use memPointer to return XML representing an entity that is not stored as a stand-alone file.

If you do not supply memPointer, set it to the Unknown value (?).

Caution: Supplying both filePath and memPointer is an error.
If the application does not implement this callback, or if the callback sets both filePath and memPointer to the Unknown value (?), the entity is resolved according to the following rules (which are also the rules that the Progress XML DOM interface uses):

If the location given in the XML source is a relative path and the SAX-reader:SCHEMA-PATH attribute has been set, try appending the relative path to each entry in SCHEMA-PATH and retrieving the file there.

If the location is a relative file path and the SAX-reader:SCHEMA-PATH attribute has the Unknown value (?), try retrieving the file relative to the working directory.

If the location given in the XML source is an absolute path to a local file or if it is an HTTP URI, try retrieving the file at the specified location.

If the file cannot be found, Progress calls the FatalError callback (if there is one) and stops processing the XML.

StartDocument

Invoked when the XML parser detects the start of an XML document.
Syntax
PROCEDURE StartDocument: 
StartDocument does not provide any data.

StartElement

Invoked when the XML parser detects the beginning of an element.
Syntax
PROCEDURE StartElement:
  DEFINE INPUT PARAMETER namespaceURI AS CHARACTER. 
  DEFINE INPUT PARAMETER localName    AS CHARACTER. 
  DEFINE INPUT PARAMETER qName        AS CHARACTER. 
  DEFINE INPUT PARAMETER attributes   AS HANDLE. 
namespaceURI
A character string indicating the namespace URI of the element.

If namespace processing is not enabled or the element is not part of a namespace, the string is of length zero.
localName
A character string indicating the non-prefixed element name.

If namespace processing is not enabled, the string is of length zero.
qName
A character string indicating the actual name of the element in the XML source.

If the name has a prefix, qName includes it, whether or not namespace processing is enabled.
attributes
A handle to a SAX-attributes object, which provides access to all attributes specified for the element.

If the element has no attributes, attributes is still a valid handle, and the NUM-ITEMS attribute is zero.

For every invocation of StartElement, there is a corresponding invocation of EndElement.

The contents of the element are reported in sequential order before the corresponding EndElement is invoked.

When StartElement returns, the SAX-attributeS object, which was created by Progress, is deleted by Progress.
Note: If the application deletes it first, however, no harm is done.

StartPrefixMapping

Invoked when the XML parser detects that a prefix associated with namespace mapping is coming into scope.
Note: This callback is invoked only when namespace processing is enabled.
Syntax
PROCEDURE StartPrefixMapping:
  DEFINE INPUT PARAMETER prefix AS CHARACTER. 
  DEFINE INPUT PARAMETER uri    AS CHARACTER. 
prefix
A character string representing the prefix for a namespace declaration.
uri
A character string representing the URI that identifies the namespace being declared.

This callback does not normally need to be implemented, since the information it provides is not required for normal namespace processing. But it might be useful, and even required, in some situations.

UnparsedEntityDecl

Invoked when the XML parser detects an entity that it does not parse (where “unparsed entity” has the definition given in the XML 1.0 specification).
Syntax
PROCEDURE UnparsedEntityDecl:
  DEFINE INPUT PARAMETER name         AS CHARACTER. 
  DEFINE INPUT PARAMETER publicID     AS CHARACTER. 
  DEFINE INPUT PARAMETER systemID     AS CHARACTER. 
  DEFINE INPUT PARAMETER notationName AS CHARACTER. 
name
A character string indicating the name of the entity.
publicID
Optional. A character string indicating the public identifier of the entity.

If publicID is not supplied, the character string is of length zero.
systemID
Optional. A character string representing the system identifier of the entity.

If systemID is not supplied, the character string is of length zero.

systemID must be one of the following:

Absolute file path

Relative file path

Absolute URI

notationName
A character string indicating the name of the notation associated with the entity.

Warning

Invoked to report a warning.
Syntax
PROCEDURE Warning:
  DEFINE INPUT PARAMETER errMessage AS CHARACTER.  
errMessage
A character string indicating the error message.

A warning is a condition that is less severe than an error or a fatal error, as determined by the XML parser.

After this callback is invoked, the parser continues where it left off.